NetCloak 3.0 User's Guide: Commands: Server Information

	Version 3.0 User's Guide

Commands: Server Information	Previous \| Next Contents

<INSERT_HOST>

Most browsers now support the "Host" field in the HTTP header. The Host field specifies the name of the server that the user has requested the document from. In most cases, this field will be the domain name of your server, or its IP address if the requested URL was specified by IP address.

This command can be very helpful in two situations. First, if your server has multiple domain names associated with it, the Host field is an excellent way to find out which domain name was requested by the client. For details on supporting multiple domains with the Host field, see the SHOW_HOST section below. Second, if you serve your Web site from multiple servers, you can create pages that are sensitive to the server they are being served from.

The INSERT_HOST command simply inserts the domain name (or IP address) that the URL specified when requesting the page.

Note that some older browsers do not send the Host field in the HTTP header. When pages are accessed by these clients, the INSERT_HOST command will not insert anything.

<HIDE_HOST operator host1 host2 ...>
<SHOW_HOST operator host1 host2 ...>

These commands allows you to hide or show portions of a page based upon the domain name (or IP address) as specified in the URL used to access the page. Text after the HIDE_HOST command will be hidden if the requested host satisfies the comparison with any of the host parameters. Text after the SHOW_HOST command will be shown if the requested host satisfies the comparison with any of the host parameters.

If the comparison operator is omitted from the command, a "contains" text comparison is used, so that a host name containing any one of the following parameters causes text to be hidden.

For example, assume your Web server is used to serve pages for three different domains: "www.greg.com", "www.peter.com", and "www.bobby.com". Each of these domain names points to the same address, which is the address of your server, and each web site is served from a sub-folder within the root folder (called "greg", "peter", and "bobby"). The default page for your server, at the root level, could be:

    <HIDE><SHOW_HOST IS "www.greg.com">    <REDIRECT "http://www.brady.com/greg/">    <HIDE><SHOW_HOST IS "www.peter.com">    <REDIRECT "http://www.brady.com/peter/">    <HIDE><SHOW_HOST IS "www.bobby.com">    <REDIRECT "http://www.brady.com/bobby/">    <SHOW>    The requested host is unknown. Please select from the following list of domains: ...

In this case, the SHOW_HOST command is used to select a REDIRECT command which sends the client to the correct default page for the domain. If the Host isn't recognized (most likely due to lack of support for the field in the browser), a default page is shown to the user so they can select the domain they are looking for.

Note that the MACRO command could be used in place of the REDIRECT commands to reduce processing, although the relative paths for URLs in the individual Home Pages could be confused. See the MACRO command for additional information.

<INSERT_HEADER>

The INSERT_HEADER command inserts the entire HTTP request header into the HTML document.

It is rare that you would want to display the HTTP header of an incoming request back to the user. There is, however, at least one very good reason for doing this. As new browsers become available with new HTTP features, you will want to add support for them into your documents. By using the INSERT_HEADER command in a few test pages, you can see exactly what information is being sent by various browsers. This makes it easy to try out different browsers on your pages to see just what the browser is sending so that you know what to look for when you are developing new pages.

The usage of this command is simple, and looks like this:

    <PRE>    <INSERT_HEADER>    </PRE>

We use the <PRE> HTML tag so that line breaks are displayed on the browser correctly. These formatting tags are not required, but the header will most likely be difficult to read without them.

<HIDE_HEADER operator text1 text2 ...>
<SHOW_HEADER operator text1 text2 ...>

The Web is based upon the HTTP protocol, which is constantly evolving. Every request that comes into your server is in the form of an HTTP header request that may have additional information that is not available via some other NetCloak command. The HEADER commands give you the ability to look into the header even when there is no direct NetCloak command for checking a particular piece of information.

The HIDE_HEADER command will hide HTML following it if the HTTP request header satisfies the comparison with any of the given text parameters.

The SHOW_HEADER command will "turn the stream on" when the HTTP request header satisfies the comparison with any of the given text parameters. Let's look at the SHOW version of these commands for an easier explanation of how this works.

If the comparison operator is omitted, a "contains" text comparison is performed, so text is shown if the current HTTP request header contains any one of the given text parameters.

The specified text can be an acceptable file type or language, the requested URL, or any other information included in incoming HTTP requests.

For example, many browsers support a field which specifies the languages they can accept and display. If you would like to selectively serve files in various languages, you can use this field to automatically select text to be displayed. For example, to display a section of text in French to browsers that support it, you might use:

    <HIDE><SHOW_HEADER CONTAINS "Accept-Language: fr">    Bon jour!
    <FLIPMODE>    Hello!
    <SHOW>

In this example, if the browser sends the appropriate field, the French text will automatically be displayed by NetCloak.

The HTTP header can also be used to help determine file types the browser can accept and more. Essentially any information that the browser sends to the server is yours for the asking.

<INSERT_REFERRER>

This command will insert the URL of the last page visited into your document at the specified point. The URL will be exactly as reported by the browser, including server name and path and search arguments.

Here is an example:

    You just came from: <INSERT_REFERRER>.
    If you want, you can <A HREF="<INSERT_REFERRER>">Go Back!</A>

Note that this command will not work if the browser does not report the last page the user visited. In general, the referrer will be reported when the user clicks on a hypertext link to access the page. However, if the user manually enters the URL, the browser may not send the referrer, since the page the user was on when they entered the URL doesn't actually reference the page being served.

You can avoid giving the user a link to a non-existent referring page using a HIDE_REFERRER or SHOW_REFERRER command, described below.

Since "REFERRER" is commonly misspelled "REFERER" (including in early versions of the Internet specification for HTTP), NetCloak also supports that spelling for all REFERRER commands.

<HIDE_REFERRER operator referrer1 referrer2 ...>

This command hides the HTML text from users based on the last HTML document they accessed (the document that "referred" the user to this one). This allows you to tailor your document depending on where the user has been.

If the comparison operator is omitted, a "contains" text comparison is performed with the listed referrer values.

Note that if a user types an URL into their Web browser to get to your page, there will be no referrer, since the page the user was on when they entered the URL doesn't actually reference the page being served.

Some browsers may not support the Referrer field, and if the browser doesn't send it, NetCloak won't be able to use it. You can check for the existence of the field by using the command alone, with no referrers specified, or by using the EXISTS comparison operator. In other words, <HIDE_REFERRER> or <HIDE_REFERRER EXISTS> will hide the text following it whenever a referrer is known.

<SHOW_REFERRER operator referrer1 referrer2...>

HTML text that follows this command will be visible to users when the most recent document they visited in their web browser satisfies the comparison with at least one of the specified "referrer" parameters.

If the comparison operator is omitted, NetCloak will show text if the referring page's URL contains any one of the listed referrer values.

For example, if your site was selected as the Cool Site of the Day, you might add this to your Home Page:

    <HIDE>    <SHOW_REFERRER CONTAINS Cool>    Welcome, Cool Site of the Day users!
    <SHOW>

This would show the text only to people who had just come from a page with the word "Cool" in the URL.

Use <SHOW_REFERRER> with no parameters, or <SHOW_REFERRER EXISTS>, to make sure the browser supports the referrer field and avoid providing a "broken" link to a nonexistent referrer, like this:

    <HIDE><SHOW_REFERRER>    You just came from <INSERT_REFERRER>.
    <A HREF="<INSERT_REFERRER>">Go back there!</A>    <FLIPMODE>    Sorry, your browser does not support referrers, or you entered the URL for  this page manually.
    <SHOW>

<INSERT_THISURL>

The INSERT_THISURL command ("This URL"), which accepts no parameters, will cause the file path and document name of the current page to be inserted into the page. For example, if the URL for a page is:

    http://www.web.com/bob/page.html$path?qry

the INSERT_THISURL command would insert:

    /bob/page.html

With servers that support virtual hosting of multiple Web sites, the path will be relative to the root folder for the requested site.

The INSERT_THISURL could be used in hidden fields on HTML forms to tell a forms processing CGI the URL of the entry form. It might also be used to create a "reload page" link, or to give the user additional feedback on how your site is set-up.

<HIDE_THISURL operator url1 url2 ...>

If the URL of the current page satisfies the comparison with any of the listed URL parameters, then this command "shuts off" the flow of text to the browser.

If the comparison operator is omitted, then the comparison is satisfied when the URL of the current page contains any one of the given URL parameters.

With the THISURL commands, NetCloak allows you to essentially create self-aware pages. By using SHOW_THISURL and HIDE_THISURL, you can create pages that change when they are moved from one folder (or server) to another. These commands can also be used in your macro file to create macros that vary depending on the page they are used on. In short, they allow you to create more portable, re-usable HTML.

<SHOW_THISURL operator url1 url2 ...>

This is the SHOW version of the HIDE_THISURL command above.

Here's an example:

    <HIDE><SHOW_THISURL CONTAINS TestFolder>    This page is in the folder 'TestFolder', and is still being tested. When    the file is moved into its final place on my site, this test message will   disappear.
    <FLIPMODE>    This page is now in production use.
    <SHOW>

When a non-existent page is requested and the error page is served, "THISURL" is the requested (non-existent) URL. This makes the SHOW_THISURL command useful for making a "smart" error page. If users have a typo in their URL, the error page can automatically redirect them to the page they were looking for.

    <HIDE><SHOW_THISURL CONTAINS faq>    <REDIRECT "http://my.server/questions/faqlist.html">    <SHOW>

You can use a similar technique to automatically redirect users accessing obsolete pages by putting the URL of the obsolete page in the SHOW_THISURL command and the new URL in the REDIRECT command.

With the example above on your error page, users who request a page that does not exist but contains "FAQ" will be automatically redirected to the FAQ List page.

Path and Search Arguments

In an HTTP URL, there are three parts of the URL that come after the server name. The first is a path to the requested file. The second part, called the "path arguments," follows the name of the requested file. In MacOS web servers, the path arguments are separated from the filename by a dollar sign character ('$'). Following the path arguments is the third part of the URL, called the "query arguments" or "search arguments." The search arguments are separated from the path arguments (or the filename, if there are no path arguments) by a question mark character ('?'). Both path arguments and search arguments are URL encoded by browsers (in other words, all non-alphanumeric characters are turned into a percent sign '%' followed by the two-digit hexadecimal ASCII code for the character). Here is an example URL containing both path arguments and search arguments:

    http://www.maxum.com/netcloak/sample.html$path%20Args?search%20Args

In this example the path arguments consist of the text "path Args"(which has been URL-encoded, turning the space character into "%20"), and the search arguments consist of the URL-encoded text "search Args". It is important not to confuse path arguments with the requested file path. In the example above, the file path is "/netcloak/sample.html".

Path and search arguments can be used to send additional data to NetCloak to be used in processing cloaked pages, simply by appending them to the URL of any cloaked page, then using the following commands within the cloaked pages.

<INSERT_PATH>

The INSERT_PATH command inserts the path arguments for the requested URL into the cloaked page. If there are no path arguments in the requested URL, this command does nothing.

If the file "/netcloak/sample.html" in the above example contained the following HTML:

    This text follows the dollar sign in the requested URL: <INSERT_PATH>

The page seen at the browser would contain:

    This text follows the dollar sign in the requested URL: path args

Important Note: If you are using the NetCloak ACGI by calling it directly in your URLs, like this:

    "http://www.yourdomain.com/NetCloak.acgi$/somefile.html"

...then the path arguments are used to send the URL of the cloaked file to NetCloak, and are not available for you to use for other purposes. In this case, the INSERT_PATH command will insert the path to the cloaked file.

<HIDE_PATH operator path1 path2 ...>
<SHOW_PATH operator path1 path2 ...>

The HIDE_PATH command turns off the flow of text in the page if the path arguments in the requested URL satisfies a comparison with any of the path parameters listed in the command.

The SHOW_PATH command turns on the flow of text if the path arguments satisfy the comparison.

A "contains" comparison is performed if no comparison operator is used.

The SHOW_PATH command can be useful when you want one page to contain all the logic for some interactive process, like an online questionnaire or game. Rather than spreading the logic for the interaction across multiple cloaked pages, you can put it all in one cloaked page, and use path arguments to determine which part of the process to send to the browser. An excellent example of this is the "regkillerapp.html" example included in the NetCloak package.

In the example, a form is submitted and processed by the same page, based on the path argument. The form command looks like this:

    <FORM METHOD=POST ACTION="regkillerapp.html$step2">

Notice the path argument specified, "Step2". Later in the page, the form is processed by enabling one section of HTML using the NetCloak command:

    <HIDE><SHOW_PATH IS "step2">

Similarly, the form itself must be hidden once it has been submitted. This can be done like this:

    <HIDE>    <SHOW_PATH IS "step1">    <SHOW_PATH #EXISTS>

This shows the form when either the first step is specified by the path argument, or when no path argument exists (as would be the case when the form is linked to from another page).

<INSERT_SEARCH>

The INSERT_SEARCH command inserts the search arguments for the requested URL into the cloaked page. If there are no search arguments in the requested URL, this command does nothing.

If the file "/netcloak/sample.html" in the INSERT_PATH example contained the following HTML:

    This text follows the question mark in the requested URL: <INSERT_SEARCH>

Then the browser would see:

    This text follows the question mark in the requested URL: search args

Note: When an HTML form specifies a method of GET instead of POST, the data in the form fields are appended to the URL specified in the action of the form, as search arguments. The SEARCH commands can be used to look at the raw form data. See the section "Commands: Variables" for more information.

<HIDE_SEARCH operator search1 search2 ...>
<SHOW_SEARCH operator search1 search2 ...>

HIDE_SEARCH turns off the flow of text in the page if the search arguments in the requested URL satisfy the comparison with any of the parameters listed in the command. SHOW_SEARCH turns on the flow of text if the search arguments in the requested URL satisfy the comparison.